Skip to content

Conversation

@cafalchio
Copy link
Contributor

@cafalchio cafalchio commented Dec 18, 2025

Summary

This PR adds a MCP Server in Python that provides QR code generation and decoding capabilities. - closes #919

Server Details

  • Name: your-server-name
  • Location: mcp-servers/python/qr_code_server/
  • Transports: STDIO, HTTP
  • Tools:
    • generate_qr_code: Generate QR codes from text or data
    • decode_qr_code: Decode QR codes from image files
    • generate_batch_qr_codes: Generate multiple QR codes efficiently
    • validate_qr_data: Validate and analyze QR code data before generation

Testing

  • Unit tests pass (95% coverage)
  • Integration tests with ContextForge Gateway
  • Linting passes (ruff)
  • Type checking passes (mypy), few exceptions
  • Container builds successfully

Documentation

  • Comprehensive README.md
  • Usage examples
  • API documentation

Checklist

  • Follows best practices
  • Includes all required files (Makefile, Containerfile, tests)
  • No secrets or credentials committed
  • Apache 2.0 license (or compatible)

@cafalchio
Copy link
Contributor Author

Address issue #919

@crivetimihai
Copy link
Member

Very cool. Thanks for the PR.

@crivetimihai crivetimihai added the blocked Blocked by some other predecessor issue or PR. See notes. label Jan 13, 2026
@crivetimihai crivetimihai self-assigned this Jan 14, 2026
@crivetimihai crivetimihai removed the blocked Blocked by some other predecessor issue or PR. See notes. label Jan 15, 2026
cafalchio and others added 24 commits January 15, 2026 03:51
    -Removed extra comments
    -Added info when loaded
    -Removed wrong validation
 - implement create_qr
 - implemented simple happy path unit test
    - Added base64 output
    - Added error handling
    - Added png, svg and ascii formats
    - Added tests to cover generator changes
    - It will check if user input has filename on it
    - check if filename.ext has the correct ext
    - It creates the output folder if it does not exist
     - save method added to allow use as qrcode image
    - Uses qrcode image factory to generate images
    - Removed ascii logic from generator
    - improved output path handling
    - remove code used to run locally
    - test for multiple formats PNG, SVG, ASCII
    - test for error handling
    - test create qr base64
…anage the following cases

    -  case 1: output_path is a folder
    - case 2: output_path has file extension
    - case 3: output_path has filename without extension
    - case 4: output_path does not have filename
    - Decoupled qr image generation from the create_qr_code
    - Improved Ascii save to handle BytesIO for batch zip generation
    - Handle errors
    - Added tests to get 100% coverage
    - Test manually to check created files
    - changed ascii filename to have extension ascii
    - Created a image generator to handle batch
    - handled errors
    - changed ascii format to have ascii extension
cafalchio and others added 25 commits January 15, 2026 03:52
    - Added Log when successfull
    - added log for success false
…t_path

Fix edge cases in file path resolution:
- Handle filenames with non-matching extensions (e.g., file.jpg -> file.jpg.png)
- Handle filenames ending with dot (e.g., weird. -> weird.png)
- Only skip extension appending when existing extension matches target format

Signed-off-by: Mihai Criveti <[email protected]>
Security fixes:
- Fix Containerfile build order (copy src/ before pip install)
- Add path traversal validation for naming_pattern to prevent zip-slip

Correctness fixes:
- Populate file_path, zip_file_path, output_directory in responses
- Use config values for batch defaults (size, output_directory, zip_output)
- Use config.decoding.preprocessing_enabled as default
- Fix wrong request names in logging (decode/validate used batch name)
- Convert NumPy arrays to lists for JSON serialization
- Fix README to show correct zip filename (qr.zip not qr_batch.zip)
- Fix test using wrong field name (version -> target_version)

Signed-off-by: Mihai Criveti <[email protected]>
Validation fixes:
- Preserve whitespace in QR data (don't strip during validation)
- Clamp border to valid range [0, 100] (was only capping max)
- Add image_format validation against config.supported_image_formats
- Consistent data length validation in batch (use actual length)

Container fixes:
- Switch to opencv-python-headless (works on slim containers)

Test additions:
- Add tests for naming_pattern path traversal rejection
- Add tests for border validation clamping

Code cleanup:
- Remove unnecessary UTF-8 encoding declarations (ruff UP009)

Signed-off-by: Mihai Criveti <[email protected]>
…rrection

Fixes:
- Add border and error_correction to BatchQRGenerationRequest model
- Pass border/error_correction to index_image_generator
- Add format validation to single QR generation (consistency with batch)
- Update server.py to expose border/error_correction for batch

Documentation:
- Update README examples to match actual output format
- Document that image_format is validation-only (auto-detection used)
- Add border/error_correction parameters to batch docs

Test fix:
- Use == instead of is for string comparison in format test

Signed-off-by: Mihai Criveti <[email protected]>
@crivetimihai crivetimihai force-pushed the feature/qr-code-server branch from 6e7b68b to 9df68eb Compare January 15, 2026 09:30
@crivetimihai crivetimihai merged commit 79324e2 into IBM:main Jan 15, 2026
2 checks passed
@crivetimihai
Copy link
Member

crivetimihai commented Jan 15, 2026

Thanks @cafalchio for this great contribution! 🎉

I've rebased the branch onto main and made some fixes to address issues found during review. Here's a summary of the changes:

Security Fixes

  • Path traversal protection: Added validation to naming_pattern to prevent ../ or absolute paths escaping output_directory
  • Container hardening: Switched to opencv-python-headless (works on slim containers without GUI libs)

Correctness Fixes

  • Containerfile build order: Moved COPY src/ before pip install -e . (hatchling needs source at build time)
  • Response fields: Now properly populating file_path, zip_file_path, and output_directory in results
  • Config consistency: Batch generation now honors border and error_correction from config (was using hardcoded defaults)
  • Format validation: Single QR now validates format against config (consistent with batch)
  • Logging: Fixed wrong request names in queue logging for decode/validate
  • NumPy serialization: Convert position arrays to lists for JSON compatibility
  • Border validation: Clamp to valid range [0, 100] (was only capping max, not min)
  • Whitespace handling: Preserve whitespace in QR data (removed .strip() that was modifying input)

Documentation

  • Updated README examples to match actual output
  • Documented that image_format is validation-only (actual format is auto-detected)
  • Added border and error_correction parameters to batch docs

Tests

  • Added tests for path traversal rejection (5 parametrized cases)
  • Added tests for border clamping (negative and large values)
  • Fixed test using wrong field name (versiontarget_version)
  • Fixed string comparison (is==)

All 97 tests passing with 94% coverage - awesome!

@cafalchio
Copy link
Contributor Author

Hi @crivetimihai, thank you very much for fixing it. I am glad to have made my first contribuition. :)

@crivetimihai
Copy link
Member

Thank you for contributing, great PR / MCP Server!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sample MCP Server - Python (qr-code-server)

2 participants